WHSL 0.0 pre-release ALPHA
Scripting How-To/Readme
==========================

The WarHammer Scripting Language (WHSL) is a language created specifically for
WH2KPC.  As of this version, it consists solely of declarations and resource
pictures.  A WHSL source code (unfinished) is called a "code", and ends in 
".whc".  A WHSL resource file (unfinished) is called a "resource", and ends in
".whr".  A finished WHSL code includes the .whc file and the .whr file, and is
called a "plugin", with a ".whp" ending.  If installed correctly, it can modify
or add to what WH2KPC does.  For now, it is only used for army creation (i.e.:
Space Marines, Tyranids, etc.).  Eventually, WHSL will be used for plugins for
audio, music, graphics, game interpretation, even multi-lingual support!  Below
is a basic outline of the current WHSL language, and how to create a basic army.


First off, you should know how things are declared in WHSL.  First, a primary variable
is declared:

	PLUGIN
	{

Inside the "{"'s, the secondary variables are declared:

	PLUGIN
	{
		.TYPE=PTYPE_ARMY
		.NAME="Space Marines Army"
		.AUTHOR="Joshua Foster (JF Software)"
		.VERMAJ=0
		.VERMIN=0
		.VERSTAT="pre-release ALPHA"
		.RESFILE="SpaceMarines.whr"
	}

The secondary variables must ALWAYS have a period (.) in front of them, because
they are secondary to PLUGIN (in this case).  If there are multiple arguments for
a secondary variable, then they are listed in parentheses ( ):

	.IDLIST=(35,21,22,23,24,16,3,25,26,27,28,29)

There can even be secondary variables inside secondary variables.  They are
declared the same way as from primary to secondary.  Also, take note:  You can
put in as much or as little whitespace (spaces, TABs, and ENTERs) as you want.


There are three variable types in WHSL: STRING, NUMBER, and BOOLEAN.  String
values are letters and characters, and must be surrounded in double-quotes (").
String values can only be up to 64 characters in length.  Number values are numbers,
and are typed as they are (no commas).  Boolean values are TRUE/FALSE, and must
be typed in UPPERCASE.


There are currently four primary variables.  They are:
  - PLUGIN: Contains variables describing the plugin.
  - WEAPON: Contains variables describing ONE weapon (army plugins only!)
  - DUALWEAPON: Contains variables describing ONE set of dual weapons
    (army plugins only!)
  - CHARACTER: Contains variables describing ONE character (army plugins only!)


Below is a complete reference of all commands in WHSL.

========================
Primary variable: PLUGIN
Plugin types:     ALL
Description:      Contains variables describing the plugin
========================
.TYPE
-----
Variable type: NUMBER
Description:   Tells WHSL what type of plugin this is. (default=1)
Constants:     PTYPE_ARMY=1     - This plugin is an army.
               PTYPE_SOUND=2    - This plugin involves the handling of sound
                                  effects. (NOT SUPPORTED YET)
               PTYPE_MUSIC=3    - This plugin involves the playing of background
                                  music. (NOT SUPPORTED YET)
               PTYPE_GRAPHICS=4 - This plugin involves the drawing of graphics.
                                  (NOT SUPPORTED YET)
               PTYPE_GAMEPLAY=5 - This plugin involves how the game is played
                                  (rule interpretation, user interface, etc.)
                                  (NOT SUPPORTED YET)
               PTYPE_MISC=6     - This plugin does not follow one of the above
                                  categories (NOT SUPPORTED YET)

.NAME
-----
Variable type: STRING
Description:   The full name of the plugin. (default="")

.AUTHOR
-------
Variable type: STRING
Description:   The name of the author of the plugin. (default="")

.VERMAJ
-------
Variable type: NUMBER
Description:   The major version number of the plugin.  Ranges
               from 1 to 99. (default=1)
Example:       If the version was 2.00, then .VERMAJ would be =2

.VERMIN
-------
Variable type: NUMBER
Description:   The minor version number of the plugin.  Ranges
               from 1 to 99. (default=0)
Example:       If the version was 2.00, then .VERMIN would be =0

.VERSTAT
--------
Variable type: STRING
Description:   Any additional version information. (default="")
Example:       "release BETA"

.RESFILE
--------
Variable type: STRING
Description:   The filename of the associated resource file.  If no
               resource file is required, then this variable is not
               required.  (Only include filename, not full path!)


========================
Primary variable: WEAPON
Plugin types:     ARMY
Description:      Contains variables describing ONE weapon
========================
.ID
---
Variable type: NUMBER
Description:   The ID number of the weapon.  Ranges from 1 to 32767.

.NAME
-----
Variable type: STRING
Description:   The name of the weapon. (default="")

.TWIN
-----
Variable type: BOOLEAN
Description:   If TRUE, then the weapon is a twin-linked.  If FALSE,
               then the weapon is single. (default=FALSE)

.RANGE
------
Variable type: NUMBER
Description:   The range of the weapon.
Constants:     WRANGE_TEMPLATE=-1 - Weapons uses the template for range.

.GUESSRANGE
-----------
Variable type: BOOLEAN
Description:   If TRUE, then ???.  If FALSE, then ???. (default=FALSE)

.STRENGTH
---------
Variable type: NUMBER
Description:   The strength of the weapon.
Constants:     WSTRENGTH_TARGETT=-1  - Weapon's strength is target's
               toughness.
               WSTRENGTH_ATTACKS=-2  - Weapon's strength is attacker's
               strength.
               WSTRENGTH_ATTACKS2=-3 - Weapon's strength is twice of
               attacker's strength, up to 10.

.PENETRATION
------------
Variable type: NUMBER
Description:   The penetration of the weapon.
Constants:     WPENE_NOSAVE=-1: Target gets no armor save.

.TYPE
-----
Variable type: NUMBER
Description:   The weapon type of the weapon. (default=0)
Constants:     WTYPE_NONE=0           - None
               WTYPE_PISTOL=1         - Pistol
               WTYPE_PISTOLP=2        - Plasma pistol
               WTYPE_RAPID=3          - Rapid fire
               WTYPE_RAPIDP=4         - Rapid fire plasma
               WTYPE_BLAST=5          - Blast
               WTYPE_ASS1=6           - Assault 1-shot
               WTYPE_ASS1BLAST=7      - Assault 1-shot blast
               WTYPE_ASS1MELTA=8      - Assault 1-shot melta
               WTYPE_ASS1LAUNCH=9     - Assault 1-shot launcher
               WTYPE_ASS1BLAUNCH=10   - Assault 1-shot blast launcher
               WTYPE_ASS1FUSION=11    - Assault 1-shot fusion
               WTYPE_ASS2=12          - Assault 2-shot
               WTYPE_ASS3=13          - Assault 3-shot
               WTYPE_ASS4=14          - Assault 4-shot
               WTYPE_ASS5BLAST=15     - Assault 5" blast
               WTYPE_HEAVYD6=16       - Heavy D6 scatter
               WTYPE_HEAVY1=17        - Heavy 1-shot
               WTYPE_HEAVY1BLAST=18   - Heavy 1-shot blast
               WTYPE_HEAVY1BLASTP=19  - Heavy 1-shot plasma blast
               WTYPE_HEAVY1MELTA=20   - Heavy 1-shot melta
               WTYPE_HEAVY1SNIPER=21  - Heavy 1-shot sniper
               WTYPE_HEAVY1LAUNCH=22  - Heavy 1-shot launcher
               WTYPE_HEAVY1BLAUNCH=23 - Heavy 1-shot blast launcher
               WTYPE_HEAVY2=24        - Heavy 2-shot
               WTYPE_HEAVY3=25        - Heavy 3-shot
               WTYPE_HEAVY3JAM=26     - Heavy 3-shot jam


============================
Primary variable: DUALWEAPON
Plugin types:     ARMY
Description:      Contains variables describing ONE set of dual weapons
                  You must already have WEAPON primaries for BOTH weapons
                  before the DUALWEAPON primary.
============================
.ID
---
Variable type: NUMBER
Description:   The ID number of the dual-weapon.  Ranges from 1 to 32767.
               Must fit in WEAPON ID list (can't be the same as a WEAPON ID).

.NAME
-----
Variable type: STRING
Description:   The name of the dual-weapon. (default="")

.SUB1ID
-------
Variable type: NUMBER
Description:   The ID of the first weapon.

.SUB2ID
-------
Variable type: NUMBER
Description:   The ID of the second weapon.


===========================
Primary variable: CHARACTER
Plugin types:     ARMY
Description:      Contains variables describing ONE character
===========================
.ID
---
Variable type: NUMBER
Description:   The ID number of the character.  Ranges from 1 to 32767.

.NAME
-----
Variable type: STRING
Description:   The name of the character. (default="")

.UNITID
-------
Variable type: NUMBER
Description:   The unit type this character belongs in.
Constants:     UTYPE_HQ=1     - An HQ unit.
               UTYPE_ELITES=2 - An Elites unit.
               UTYPE_TROOPS=3 - A Troops unit.
               UTYPE_FAST=4   - A Fast Attack unit.
               UTYPE_HEAVY=5  - A Heavy Support unit.

.POINTCOST
----------
Variable type: NUMBER
Description:   The point cost of the character.

.WS
---
Variable type: NUMBER
Description:   The WS statistic of the character.

.BS
---
Variable type: NUMBER
Description:   The BS statistic of the character.

.S
--
Variable type: NUMBER
Description:   The S statistic of the character.

.T
--
Variable type: NUMBER
Description:   The T statistic of the character.

.W
--
Variable type: NUMBER
Description:   The W statistic of the character.

.I
--
Variable type: NUMBER
Description:   The I statistic of the character.

.A
---
Variable type: NUMBER
Description:   The A statistic of the character.

.LD
---
Variable type: NUMBER
Description:   The Leadership statistic of the character.

.SV
---
Variable type: NUMBER
Description:   The SV statistic of the character.

.WEAPONLIST
-----------
Variable type: PRIMARY
Description:   Contains variables for one of the weapons lists.

	.ID
	---
	Variable type: NUMBER
	Description:   The ID number of the weapon list.  Ranges
                       from 1 to 32767.

	.IDLIST
	-------
	Variable type: NUMBER (multiple)
	Description:   The weapon ID's that can be chosen from.
	               All values MUST be surrounded by parentheses.

	.COSTLIST
	---------
	Variable type: NUMBER (multiple)
	Description:   The point costs of the weapons in the list.
	               All values MUST be surrounded by parentheses,
	               and the values must correspond with those in
                       .IDLIST.

.VIEWLIST
---------
Variable type: PRIMARY
Description:   Contains variables for the different views of the
               character.

	.FRONTRESID
	-----------
	Variable type: NUMBER
	Description:   The resource ID# of the picture to show when
	               viewing the character from the front.

	.BACKRESID
	----------
	Variable type: NUMBER
	Description:   The resource ID# of the picture to show when
	               viewing the character from the back.

	.OVERRESID
	-----------
	Variable type: NUMBER
	Description:   The resource ID# of the picture to show when
	               viewing the character from overhead.

.UPGRADE
--------
Variable type: NUMBER
Description:   If this character can be upgraded, then this value is
               the character ID# of the character this can be up-
               graded to.  If this character can not be upgraded, then
               this value should be UPTYPE_NONE. (default=-1)
Constants:     UPTYPE_NONE=-1 - This character can not be upgraded.

.BASECHAR
---------
Variable type: BOOLEAN
Description:   If this character is a base character (not an upgrade of
               another character), then this should be TRUE.  If this
               character is the upgrade of another character, then this
               should be FALSE. (default=TRUE)

.REQUIRED
---------
Variable type: BOOLEAN
Description:   If .BASECHAR is TRUE, then if this character is required
               in this unit (like a Leader in SM), then .REQUIRED should
               be TRUE; otherwise FALSE.  If .BASECHAR is FALSE, then if
               this character is required with a group of non-upgraded
               characters of this type, then .REQUIRED should be TRUE;
               otherwise FALSE. (default=FALSE)

.MAXCHARS
---------
Variable type: NUMBER
Description:   The maximum number of this character in a unit.

.MINCHARS
---------
Variable type: NUMBER
Description:   The minimum number of this character in a unit.



TO DO LIST
==========
- Finish CHARACTER list
- Fix certain weapons
- Add VEHICLE primary variable
- Add events to process code
